{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Frost Number Model\n",
    "\n",
    "### Introduction to Permafrost Processes - Lesson 1\n",
    "\n",
    "This lab has been designed and developed by Irina Overeem and Mark Piper, CSDMS, University of Colorado, CO \n",
    "with assistance of Kang Wang, Scott Stewart at CSDMS, University of Colorado, CO, and Elchin Jafarov, at Los Alamos National Labs, NM. \n",
    "These labs are developed with support from NSF Grant 1503559, ‘Towards a Tiered Permafrost Modeling Cyberinfrastructure’ \n",
    "\n",
    "### Classroom organization\n",
    "\n",
    "This lab is the first in a series of introduction to permafrost process modeling, designed for inexperienced users. In this first lesson, we explore the Air Frost Number model and learn to use the CSDMS Python Modeling Toolkit ([PyMT](https://github.com/csdms/pymt)). We implemented a basic configuration of the Air Frost Number (as formulated by Nelson and Outcalt in 1987). This series of labs is designed for inexperienced modelers to gain some experience with running a numerical model, changing model inputs, and analyzing model output. Specifically, this first lab looks at what controls permafrost occurrence and compares the occurrence of permafrost in Russia. \n",
    "Basic theory on the Air Frost Number is presented in [Frost Number Model Lecture 1](https://csdms.colorado.edu/wiki/File:FrostNumberModel_Lecture1.pptx).\n",
    "\n",
    "\n",
    "This lab will likely take ~ 1,5 hours to complete in the classroom. This time assumes you are unfamiiar with the PyMT and need to learn setting parameters, saving runs, downloading data and looking at output (otherwise it will be much faster).\n",
    "\n",
    "We will use netcdf files for output, this is a standard output from all CSDMS models. If you have no experience with visualizing these files, Panoply software will be helpful. Find instructions on how to use this software.\n",
    "\n",
    "### Learning objectives\n",
    "\n",
    "#### Skills\n",
    "\n",
    "* familiarize with a basic configuration of the Air Frost Number Model\n",
    "* hands-on experience with visualizing NetCDF output with Panoply.\n",
    "\n",
    "\n",
    "#### Topical learning objectives:\n",
    "\n",
    "* what is the primary control on the occurrence of permafrost\n",
    "* freezing and thawing day indices and how to approximate these\n",
    "* where in Russia permafrost occurs\n",
    "\n",
    "### References and More information \n",
    "\n",
    "Nelson, F.E., Outcalt, S.I., 1987. *A computational method for prediction and prediction and regionalization of permafrost.* Arct. Alp. Res. 19, 279–288.  \n",
    "Janke, J., Williams, M., Evans, A., 2012. *A comparison of permafrost prediction models along a section of Trail Ridge Road, RMNP, CO.* Geomorphology 138, 111-120.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Air Frost number\n",
    "\n",
    "The Air Frost number uses the mean annual air temperature of a location (MAAT), as well as the yearly temperature amplitude. In the Air Frost parametrization the Mean monthly temperature of the warmest month (Tw) and coldest month (Tc) set that amplitude. The 'degree thawing days' are above 0 C, the 'degree freezing days' are below 0 C. To arrive at the cumulative freezing degree days and thawing degree days the annual temperature curve is approximated by a cosine as defined by the warmest and coldest months, and one can integrate under the cosine curve (see figure, and more detailed notes in the associated presentation).\n",
    "\n",
    "![MAAT](https://csdms.colorado.edu/mediawiki/images/thumb/CosineapproximationMAAT.png/594px-CosineapproximationMAAT.png \"Mean Annual Air Temperature\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pymt.models\n",
    "frost_number = pymt.models.FrostNumber()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Part 1\n",
    "\n",
    "Adapt the base case configuration to a mean temperature of the coldest month of *-13C*, and of the warmest month *+19.5C* (the actual values for Vladivostok in Far East Russia)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "config_file, config_folder = frost_number.setup(T_air_min=-13., T_air_max=19.5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number.initialize(config_file, config_folder)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number.update()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number.output_var_names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number.get_value('frostnumber__air')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Part 2\n",
    "\n",
    "Now run the same simulation for Yakutsk on the Lena River in Siberia. There the warmest month is again *19.5C*, but the coldest month is *-40.9C*. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args = frost_number.setup(T_air_min=-40.9, T_air_max=19.5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number.initialize(*args)\n",
    "frost_number.update()\n",
    "frost_number.get_value('frostnumber__air')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Questions\n",
    "\n",
    "Please answer the following questions in each box (**double click the box to edit**)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q1: What is the Frost Number the model returned for each of the Vladivostok and Yakutsk temperature regimes? \n",
    "\n",
    "*A1:* the answer in here."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q2: What do these specific Frost numbers imply for the likelihood of permafrost occurrence?\n",
    "\n",
    "*A2:*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q3: How do you think the annual temperature distribution would look in regions of Russia bordering the Barents Sea? \n",
    "\n",
    "*A3:*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q4: Devise a scenario and run it; was the calculated Frost number what you expected?\n",
    "\n",
    "*A4:*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q5: On the map below, find the how the permafrost is mapped in far west coastal Russia at high-latitude (e.g. Murmansk). \n",
    "\n",
    "![map_of_alaska](https://csdms.colorado.edu/mediawiki/images/Perm_ext_Russia.gif \"Alaska\")\n",
    "\n",
    "*A5:*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q6: Discuss the factors that would make this first-order approach problematic? \n",
    "*A6:*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q7: When would the temperature in the first cm in the soil be significantly different from the air temperature?\n",
    "\n",
    "*A7:*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extra Credit\n",
    "\n",
    "Now run a time series."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = pandas.read_csv(\"https://raw.githubusercontent.com/mcflugen/pymt_frost_number/master/data/t_air_min_max.csv\")\n",
    "data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number = pymt.models.FrostNumber()\n",
    "config_file, run_folder = frost_number.setup()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "frost_number.initialize(config_file, run_folder)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "t_air_min = data[\"atmosphere_bottom_air__time_min_of_temperature\"]\n",
    "t_air_max = data[\"atmosphere_bottom_air__time_max_of_temperature\"]\n",
    "fn = np.empty(6)\n",
    "\n",
    "for i in range(6):\n",
    "    frost_number.set_value(\"atmosphere_bottom_air__time_min_of_temperature\", t_air_min.values[i])\n",
    "    frost_number.set_value(\"atmosphere_bottom_air__time_max_of_temperature\", t_air_max.values[i])\n",
    "    frost_number.update()\n",
    "    fn[i] = frost_number.get_value('frostnumber__air')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "years = range(2000, 2006)\n",
    "plt.subplot(211)\n",
    "plt.plot(years, t_air_min, years, t_air_max)\n",
    "\n",
    "plt.subplot(212)\n",
    "plt.plot(years, fn)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
